.TH "gdaladdo" 1 "Mon Apr 25 2016" "GDAL" \" -*- nroff -*-
.ad l
.nh
.SH NAME
gdaladdo \- gdaladdo 
builds or rebuilds overview images
.SH "SYNOPSIS"
.PP
.PP
.nf
gdaladdo [-r {nearest,average,gauss,cubic,cubicspline,lanczos,average_mp,average_magphase,mode}]
         [-b band]*
         [-ro] [-clean] [-oo NAME=VALUE]* [--help-general] filename levels
.fi
.PP
.SH "DESCRIPTION"
.PP
The gdaladdo utility can be used to build or rebuild overview images for most supported file formats with one of several downsampling algorithms\&.
.PP
.IP "\fB\fB-r\fP \fI{nearest (default),average,gauss,cubic,cubicspline,lanczos,average_mp,average_magphase,mode}\fP:\fP" 1c
Select a resampling algorithm\&. 
.IP "\fB\fB-b\fP \fIband\fP:\fP" 1c
(available from GDAL 1\&.10) Select an input band \fIband\fP for overview generation\&. Band numbering starts from 1\&. Multiple \fB-b\fP switches may be used to select a set of input bands to generate overviews\&. 
.IP "\fB\fB-ro\fP:\fP" 1c
(available from GDAL 1\&.6\&.0) open the dataset in read-only mode, in order to generate external overview (for GeoTIFF especially)\&.  
.IP "\fB\fB-clean\fP:\fP" 1c
(available from GDAL 1\&.7\&.0) remove all overviews\&.  
.IP "\fB\fB-oo\fP \fINAME=VALUE\fP:\fP" 1c
(starting with GDAL 2\&.0) Dataset open option (format specific) 
.IP "\fB\fIfilename\fP:\fP" 1c
The file to build overviews for (or whose overviews must be removed)\&.  
.IP "\fB\fIlevels\fP:\fP" 1c
A list of integral overview levels to build\&. Ignored with -clean option\&. 
.PP
.PP
\fIMode\fP (available from GDAL 1\&.6\&.0) selects the value which appears most often of all the sampled points\&. \fIaverage_mp\fP is unsuitable for use\&. \fIAverage_magphase\fP averages complex data in mag/phase space\&. \fINearest\fP and \fIaverage\fP are applicable to normal image data\&. \fINearest\fP applies a nearest neighbour (simple sampling) resampler, while \fIaverage\fP computes the average of all non-NODATA contributing pixels\&. \fICubic\fP resampling (available from GDAL 1\&.7\&.0) applies a cubic convolution kernel\&. \fIGauss\fP resampling (available from GDAL 1\&.6\&.0) applies a Gaussian kernel before computing the overview, which can lead to better results than simple averaging in e\&.g case of sharp edges with high contrast or noisy patterns\&. The advised level values should be 2, 4, 8, \&.\&.\&. so that a 3x3 resampling Gaussian kernel is selected\&. \fICubicSpline\fP resampling (available from GDAL 2\&.0) applies a B-Spline convolution kernel\&. \fILanczos\fP resampling (available from GDAL 2\&.0) applies a Lanczos windowed sinc convolution kernel\&.
.PP
gdaladdo will honour properly NODATA_VALUES tuples (special dataset metadata) so that only a given RGB triplet (in case of a RGB image) will be considered as the nodata value and not each value of the triplet independently per band\&.
.PP
Selecting a level value like \fI2\fP causes an overview level that is 1/2 the resolution (in each dimension) of the base layer to be computed\&. If the file has existing overview levels at a level selected, those levels will be recomputed and rewritten in place\&.
.PP
For internal GeoTIFF overviews (or external overviews in GeoTIFF format), note that -clean does not shrink the file\&. A later run of gdaladdo with overview levels will cause the file to be expanded, rather than reusing the space of the previously deleted overviews\&. If you just want to change the resampling method on a file that already has overviews computed, you don't need to clean the existing overviews\&.
.PP
Some format drivers do not support overviews at all\&. Many format drivers store overviews in a secondary file with the extension \&.ovr that is actually in TIFF format\&. By default, the GeoTIFF driver stores overviews internally to the file operated on (if it is writable), unless the -ro flag is specified\&.
.PP
Most drivers also support an alternate overview format using Erdas Imagine format\&. To trigger this use the USE_RRD=YES configuration option\&. This will place the overviews in an associated \&.aux file suitable for direct use with Imagine or ArcGIS as well as GDAL applications\&. (e\&.g\&. --config USE_RRD YES)
.SH "External overviews in GeoTIFF format"
.PP
External overviews created in TIFF format may be compressed using the COMPRESS_OVERVIEW configuration option\&. All compression methods, supported by the GeoTIFF driver, are available here\&. (e\&.g\&. --config COMPRESS_OVERVIEW DEFLATE)\&. The photometric interpretation can be set with --config PHOTOMETRIC_OVERVIEW {RGB,YCBCR,\&.\&.\&.}, and the interleaving with --config INTERLEAVE_OVERVIEW {PIXEL|BAND}\&.
.PP
For JPEG compressed external overviews, the JPEG quality can be set with '--config JPEG_QUALITY_OVERVIEW value' (GDAL 1\&.7\&.0 or later)\&.
.PP
For LZW or DEFLATE compressed external overviews, the predictor value can be set with '--config PREDICTOR_OVERVIEW 1|2|3' (GDAL 1\&.8\&.0 or later)\&.
.PP
To produce the smallest possible JPEG-In-TIFF overviews, you should use : 
.PP
.nf
--config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR --config INTERLEAVE_OVERVIEW PIXEL

.fi
.PP
.PP
Starting with GDAL 1\&.7\&.0, external overviews can be created in the BigTIFF format by using the BIGTIFF_OVERVIEW configuration option : --config BIGTIFF_OVERVIEW {IF_NEEDED|IF_SAFER|YES|NO}\&. The default value is IF_NEEDED\&. The behaviour of this option is exactly the same as the BIGTIFF creation option documented in the GeoTIFF driver documentation\&. 
.PD 0

.IP "\(bu" 2
YES forces BigTIFF\&. 
.IP "\(bu" 2
NO forces classic TIFF\&. 
.IP "\(bu" 2
IF_NEEDED will only create a BigTIFF if it is clearly needed (uncompressed, and overviews larger than 4GB)\&. 
.IP "\(bu" 2
IF_SAFER will create BigTIFF if the resulting file \fImight\fP exceed 4GB\&. 
.PP

.br
.PP
See the documentation of the GeoTIFF driver for further explanations on all those options\&.
.SH "C API"
.PP
Functionality of this utility can be done from C with GDALBuildOverviews()\&.
.SH "EXAMPLE"
.PP
.PP
Create overviews, embedded in the supplied TIFF file:
.PP
.PP
.nf
gdaladdo -r average abc.tif 2 4 8 16
.fi
.PP
.PP
Create an external compressed GeoTIFF overview file from the ERDAS \&.IMG file:
.PP
.PP
.nf
gdaladdo -ro --config COMPRESS_OVERVIEW DEFLATE erdas.img 2 4 8 16
.fi
.PP
.PP
Create an external JPEG-compressed GeoTIFF overview file from a 3-band RGB dataset (if the dataset is a writable GeoTIFF, you also need to add the -ro option to force the generation of external overview):
.PP
.PP
.nf
gdaladdo --config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR
         --config INTERLEAVE_OVERVIEW PIXEL rgb_dataset.ext 2 4 8 16
.fi
.PP
.PP
Create an Erdas Imagine format overviews for the indicated JPEG file:
.PP
.PP
.nf
gdaladdo --config USE_RRD YES airphoto.jpg 3 9 27 81
.fi
.PP
.SH "AUTHORS"
.PP
Frank Warmerdam warmerdam@pobox.com, Silke Reimer silke@intevation.de 
